home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / Graphic Elements 3 / LibHdrs / DispCtrl.h < prev    next >
Text File  |  1995-06-07  |  10KB  |  356 lines
  1. /*
  2.     DispCtrl.h
  3.     
  4.     Display Controller routines for Graphic Elements
  5.     
  6.     Copyright 1994 by Al Evans. All rights reserved.
  7.     
  8.     3/7/94
  9.  
  10.     Updated 5/25/95 for Graphic Elements version 3.0
  11.     
  12. */
  13.  
  14. #ifndef DISPCTRL
  15. #define DISPCTRL
  16.  
  17. #include "Defs.h"
  18.  
  19.  
  20. #ifdef __cplusplus
  21. extern "C" {
  22. #endif
  23.  
  24.  
  25. //Creation of new GEWorld
  26.  
  27. /*
  28.     Returns pointer to a new GEWorld. This world covers the area of worldPort
  29.     specified by worldRect (in port coordinates), if scale is scaleOneToOne.
  30.     
  31.     Scale determines the interpretation of the position and size of worldRect 
  32.     within worldPort. Briefly, if a GEWorld has a certain position and size in
  33.     a GrafPort at scaleOneToOne, that GEWorld will have the same *relative* position
  34.     and size, if the horizontal and vertical dimensions of the GrafPort are halved,
  35.     at a scale of 0x00008000 (0.5 in fixed-point notation). 
  36.         
  37.     If it is not nil, worldColors must be a handle to a color table appropriate 
  38.     for an 8-bit depth.
  39.     
  40. */
  41.  
  42. GEWorldPtr NewGEWorld(GrafPtr worldPort, Rect *worldRect, Fixed scale, CTabHandle worldColors);
  43.  
  44.  
  45. //Destruction of a GEWorld
  46.  
  47. /*
  48.     Disposes of a world and everything in it.
  49. */
  50.  
  51. void DisposeGEWorld(GEWorldPtr world);
  52.  
  53.  
  54. //Management of a GEWorld
  55.  
  56. /*
  57.     Set default loader function for world.  If no loader is specified when a new
  58.     Graphic Element is created, this function is used.
  59.     
  60.     In a newly-created world, this loader function is one which creates an offscreen
  61.     GWorld and loads one or more PICTS from an open resource fork into it.
  62. */
  63.  
  64. void SetDefaultLoadFunc(GEWorldPtr world, GraphicLoadFunc loader);
  65.  
  66. /*
  67.     Set frame post-processing function and data for world. If this function is
  68.     present, it will be called after every frame update.
  69. */
  70.  
  71. void SetPostProcFunc(GEWorldPtr world, FramePostProcFunc postProcFunc, Ptr postProcData);
  72.  
  73. /*
  74.  
  75.     Activate or deactivate an individual world
  76. */
  77.  
  78. void ActivateWorld(GEWorldPtr world, Boolean turnItOn);
  79.  
  80. /*
  81.     Get and set projection rate
  82.     These are NOT very useful, but MAY improve performance in some situations on
  83.     slower machines.
  84. */
  85.  
  86. void SetProjectionRate(GEWorldPtr world, short newMSPerFrame);
  87.  
  88. short GetProjectionRate(GEWorldPtr world);
  89.  
  90. /*
  91.     Control GEWorld's timer
  92. */
  93.  
  94. void StartGETimer(GEWorldPtr world);
  95.  
  96. void StopGETimer(GEWorldPtr world);
  97.  
  98.  
  99. //Returns current time in world
  100. unsigned long CurrentGETime(GEWorldPtr world);
  101.  
  102. /*    Set the number of timer milliseconds that pass per "real"
  103.     millisecond. newRate is treated as a fixed-point number,
  104.     with a two-byte positive integer and a two byte fraction,
  105.     such that a value of 0x00010000 will give a 1-to-1
  106.     correspondence between Graphic Elements "milliseconds"
  107.     and real milliseconds.
  108. */
  109.  
  110. void SetGETimerRate(GEWorldPtr world, unsigned long newRate);
  111.  
  112. //Returns current "rate" of timer in world
  113. unsigned long GetGETimerRate(GEWorldPtr world);
  114.  
  115. /*
  116.     Manipulate world coordinate system;
  117. */
  118.  
  119. /*
  120.     GetGEWorldFocus and SetGEWorldFocus should be used to "bracket" calls to
  121.     FocusOnGEWorld, in order to save and restore the previous focus.
  122. */
  123.  
  124. void GetGEWorldFocus(GEWorldPtr world, Point *currFocus);
  125. void SetGEWorldFocus(GEWorldPtr world, Point newFocus);
  126.  
  127. /*
  128.     Sets focus, i.e. coordinate system, to that of world
  129. */
  130.  
  131. void FocusOnGEWorld(GEWorldPtr world);
  132.  
  133. /*
  134.     Keeps display controller from drawing into a portion of world has been covered by other 
  135.     graphics which should be protected. The Rect is in the coordinates of the GEWorld's
  136.     enclosing GrafPort.
  137. */
  138.  
  139. void CoverRect(GEWorldPtr world, Rect *coveredRect);
  140.  
  141. /*
  142.     Like CoverRect(), but protects any region
  143. */
  144.  
  145. void CoverRegion(GEWorldPtr world, RgnHandle coveredRgn);
  146.  
  147. /*
  148.     Uncovers a rect -- opposite of CoverRect()
  149. */
  150.  
  151. void UncoverRect(GEWorldPtr world, Rect *rectToUncover);
  152.  
  153. /*
  154.     Like UncoverRect, but uncovers any region
  155. */
  156.  
  157. void UncoverRegion(GEWorldPtr world, RgnHandle rgnToUncover);
  158.  
  159. /*
  160.     Undoes the effects of ALL calls to CoverRect() or CoverRegion()
  161. */
  162.  
  163. void UncoverWorld(GEWorldPtr world);
  164.  
  165. /*
  166.     Move an entire GEWorld relative to its window
  167. */
  168.  
  169. void MoveGEWorld(GEWorldPtr world, short dh, short dv);
  170. void MoveGEWorldTo(GEWorldPtr world, short h, short v);
  171.  
  172. /*
  173.     Scale a distance to the current world's worldScale.
  174.     This is necessary ONLY in creating new Graphic Elements,
  175.     for determining size and position within a world.
  176.     
  177.     Returns value * world->worldScale / 65536. If result is 0, returns
  178.     1 if value was positive, -1 if value was negative.
  179. */
  180.  
  181. short ScaleToWorld(GEWorldPtr world, short value);
  182.  
  183. /*
  184.     Generate a frame showing the world in its current state and display it on the screen.
  185.     Should be called frequently from application program, for example once each time
  186.     through the main event loop.
  187.     
  188.     If invalidate is true, the entire world is redrawn. Otherwise, only the changed
  189.     portions of world are updated.
  190. */
  191.  
  192. // If world manager is in use for world, this will update all worlds registered with manager
  193. void DoWorldUpdate(GEWorldPtr world, Boolean invalidate);
  194.  
  195. // Updates ONLY the specified GEWorld
  196. void Update1GEWorld(GEWorldPtr world, Boolean invalidate);
  197.  
  198. /*
  199.     Call from event handler when mouse down in the window containing world.
  200.     Returns true if mouseDown was handled by a sensor, false otherwise.
  201. */
  202.  
  203. // If world manager is in use for world, this will check sensors 
  204. // in all worlds registered with manager
  205. Boolean MouseDownInSensor(GEWorldPtr world, Point gMousePt);
  206.  
  207. // Checks sensors in ONLY the specified GEWorld
  208. Boolean MouseDownIn1World(GEWorldPtr world, Point gMousePt);
  209.  
  210. //Services provided by Display Controller for Graphic Elements
  211.  
  212. //Creation and destruction
  213.  
  214. /* 
  215.     Low-level element creation. This function allocates an element, calls its
  216.     GraphicLoadFunc proc (if any), and links it into the world. In itself, it 
  217.     initializes only the fields element->objectID and element-<drawPlane (in
  218.     addition to those initialized by the GraphicLoadFunc).
  219.     
  220.     It is normally called only from a higher-level creation function.
  221. */
  222.  
  223. GrafElPtr NewGrafElement(GEWorldPtr world, OSType id, short plane, short elemSize,
  224.                             GraphicLoadFunc loadProc, short resStart, short nRsrcs);
  225.                             
  226. /*
  227.     Unlinks a graphic element from its world and disposes of it. Calls element's
  228.     cleanupProc, if any. Recursively disposes of element's slaveGrafEl(s). If element
  229.     has a masterGrafEl, sets masterGrafEl->slaveGrafEl to nil.
  230. */
  231.  
  232. void DisposeGrafElement(GEWorldPtr world, OSType objectID);
  233.  
  234. //Access
  235.  
  236. /*
  237.     Returns individual element with ID objectID
  238. */
  239.  
  240. GrafElPtr FindElementByID(GEWorldPtr world, OSType objectID);
  241.  
  242. /*
  243.     Returns first element with drawPlane == plane. For collision checking, etc.
  244. */
  245.  
  246. GrafElPtr ElementsInPlane(GEWorldPtr world, short plane);
  247.  
  248. //Control
  249.  
  250. /*
  251.     ShowElement shows or hides a Graphic Element, depending on the value of showIt
  252. */
  253.  
  254. void ShowElement(GEWorldPtr world, OSType elementID, Boolean showIt);
  255.  
  256. /*
  257.     Test whether element is presently visible
  258. */
  259.  
  260. Boolean ElementVisible(GEWorldPtr world, OSType elementID);
  261.  
  262. /*
  263.     Move graphic elements
  264. */
  265.  
  266. void MoveElement(GEWorldPtr world, OSType elementID, short dh, short dv);
  267. void MoveElementTo(GEWorldPtr world, OSType elementID, short h, short v);
  268.  
  269. // Alternate interface: avoid lookup when GrafElPtr already available, for example
  270. // in Autochange procedures.
  271. // For PtrMoveElementTo(), h and v are in absolute pixels if doScale is false
  272.  
  273. void PtrMoveElement(GEWorldPtr world, GrafElPtr element, short dh, short dv);
  274. void PtrMoveElementTo(GEWorldPtr world, GrafElPtr element, short h, short v, Boolean doScale);
  275.  
  276. /*
  277.     Sets element's plane to newPlane
  278. */
  279.  
  280. void SetElementPlane(GEWorldPtr world, OSType elementID, short newPlane);
  281.  
  282. /*
  283.     Set element's autochange parameters
  284. */
  285.  
  286. void SetAutoChange(GEWorldPtr world, OSType elementID, AutoChangeProc changeProc,
  287.                         Ptr changeData, short changeIntrvl);
  288.                         
  289. /*
  290.     Set element's collision parameters. No collision if collidePlane == 0
  291. */
  292.  
  293. void SetCollision(GEWorldPtr world, OSType elementID, CollisionProc collideProc, 
  294.                         short collidePlane);
  295.                         
  296. /*
  297.     Set element's custom dispose proc.
  298. */
  299.  
  300. void SetCleanupProc(GEWorldPtr world, OSType elementID, CleanupProc elemCleanup);
  301.  
  302. //Miscellaneous sensor services
  303.  
  304. //Add sensor to world's sensor list and make it active
  305. void AddSensorToList(GEWorldPtr world, OSType id, Rect *sensorRect);
  306.  
  307. //Remove sensor from world's sensor list and make it inactive
  308. void RemoveSensorFromList(GEWorldPtr world, OSType id);
  309.  
  310. //Set sensor's actionProc to newAction
  311. void SetSensorAction(GEWorldPtr world, OSType sensorID, SensorAction newAction);
  312.  
  313. //Get element's entry in world->sensorList, if any
  314. SListEntryPtr FindSensorListEntry(GEWorldPtr world, OSType sensorID);
  315.  
  316. /*
  317.     If anything in a world is changed from OUTSIDE the Graphic Elements system,
  318.     call this procedure with the affected rectangle.
  319. */
  320.  
  321. void ChangedRect(GEWorldPtr world, Rect *chgdRect);
  322.  
  323.  
  324. /*
  325.     GraphicLoadFunc which:
  326.     
  327.     1)    Searches to see if the required graphics are already available in this world, 
  328.         and copies their parameters if so,
  329.     2)     Otherwise, creates a new offscreen GWorld of an appropriate size, and
  330.         loads nResources PICTs from an open resource file into it, starting
  331.         at the PICT with resource number startResNum
  332.         
  333.     This is the default loaderFunc of a newly created GEWorld.
  334. */
  335.  
  336. pascal Boolean LoadPICTElement(GEWorldPtr world, GrafElPtr element,
  337.                                         short startResNum, short nResources);
  338.  
  339.  
  340. /*
  341.     GraphicLoadFunc which does nothing except initialize the appropriate fields.
  342.     For Graphic Elements which have no permanent offscreen representations, e.g.
  343.     strings or fills.
  344. */
  345.  
  346. pascal Boolean NoLoader(GEWorldPtr world, GrafElPtr element,
  347.                                         short startResNum, short nResources);
  348.  
  349.  
  350.  
  351. #ifdef __cplusplus
  352. }
  353. #endif
  354.  
  355.  
  356. #endif